ATSUBreakLine

OSStatus ATSUBreakLine (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iLineStart,
                     ATSUTextMeasurement iLineWidth,
                     Boolean iUseAsSoftLineBreak,
                     UniCharArrayOffset *oLineBreak);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iLineStart

A value of type UniCharArrayOffset. The first time you call ATSUBreakLine, pass the edge offset of the beginning of the range of text whose soft line break(s) you wish to calculate. On subsequent calls, pass the offset passed back in the previous call to ATSUBreakLine. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If the offset is outside the text buffer, ATSUBreakLine returns the result code kATSUInvalidTextRangeErr.

iLineWidth

A value of type ATSUTextMeasurement. Pass a value greater than 0 that represents the width of the line, beginning at iLineStart. To indicate the line width previously set for the line, pass the constant kATSUUseLineControlWidth, described in Line Layout Width Constant.

iUseAsSoftLineBreak

A Boolean value. Pass true if you want ATSUBreakLine to set the recommended soft line break; otherwise, false.

oLineBreak

A pointer to a value of type UniCharArrayOffset. On return, the recommended soft line break. If the line break occurs in the middle of the word, ATSUBreakLine passes back the location of the soft line break and returns the result code kATSULineBreakInWord. If ATSUBreakLine passes back the same value as you passed in iLineStart, either iLineWidth is not big enough for ATSUBreakLine to perform line breaking, or there is another input error. You must check for this condition, because ATSUBreakLine will not return an error in this case.

function result

A result code. The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encounters an error rendering or measuring a line of ATSUI text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUBreakLine function suggests and optionally sets a soft line break in a line based on the line width specified in iLineWidth.

Before calculating soft line breaks, ATSUBreakLine turns off any previously set line justification, rotation, width alignment, descent, and ascent values and treats the text as a single line. It then examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUBreakLine assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUBreakLine assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUBreakLine assigns the remaining characters to the last style run it can find.

You should call ATSUBreakLine when the user inserts or deletes text or changes text layout attributes that affect how glyphs are laid out. If the user changes attributes that don't affect glyph layout, it will pass back the previously set soft line breaks. You should call ATSUBreakLine repeatedly until it does not find any more soft line breaks.

If ATSUBreakLine does not encounter a hard line break, it uses the line width you specify to determine how many characters can fit on a line. If you pass true for iUseAsSoftLineBreak, it uses the soft line break it calculated to perform line layout on the characters. ATSUBreakLine then determines whether the characters still fit within the line. This is necessary due to end-of-line effects like swashes. When ATSUBreakLine sets a soft line break, it clear previously set soft line breaks in the line.

To implement word break hyphenation, pass false to the iUseAsSoftLineBreak parameter and call the function ATSUSetSoftLineBreak.

ATSUBreakLine suggests a soft line break each time it encounters a hard line break character like a carriage return, line feed, form feed, line separator, or paragraph separator.

SPECIAL CONSIDERATIONS

ATSUBreakLine may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.